Skip to main content

1: Onboarding Tenants

When onboarding users, also referred to as tenants or wallets, you need to use your OAuth 2.0 Client Credentials. Below, you will find the curl commands used to create an Issuer, Verifier and a Holder.

If you are using the Swagger UI to do the onboarding, you can just use the JSON body in the example requests, which is after the -d in the curl commands. The appropriate Bearer token should be included in the Authorization header for admin tasks using a browser extension like ModHeader or the x-api-key needs to be set using the Authorize button at the top right of the Swagger UI for non-admin tasks.

The difference between an Issuer, Verifier and Holder is that issuers and verifiers have privileged roles, and are therefore written to the trust registry, allowing them to issue credentials and to verify proof requests in our ecosystem. A holder is a regular tenant without a role, and therefore cannot act as an issuer or verifier. They are all "tenants", and therefore each will have a unique tenant access token.

Onboard Issuer​

Note the Authorization: Bearer <Token> used in the create tenant request:

curl -X 'POST' \
  'https://cloudapi.test.didxtech.com/tenant-admin/v1/tenants' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Token>' \
  -d '{
  "wallet_label": "Demo Issuer",
  "wallet_name": "Faber",
  "roles": [
    "issuer"
  ],
  "group_id": "API demo",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png"
}'

NB: In the above request, wallet_label is the only required field, and does not have to be unique across regular tenants; however, it must be unique when requesting roles, or if the label is already used by an actor with a role. i.e. We cannot have a new tenant sharing a label with an issuer or verifier. Additionally, wallet_name must also be unique across all wallets, and a 409 status code will be returned if there is a conflict with the wallet name or label.

If wallet_name is not requested, a random one will be generated and provided in the response.

The wallet_label is publicized to other agents when forming a connection, and the wallet_name helps to filter wallets or to fetch by wallet name using the GET /v1/tenants endpoint.

Response:

{
  "access_token": "tenant.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXRfaWQiOiJkZWEwYTlmYi0wODhkLTQ2ODktYmM5Yy04YTFiYWI5MDYxNzAiLCJpYXQiOjE3MDA2MzE4NzN9.7Pwb5Q6BKHA6N9luJH1uDiHdgSZXPWwvdV4O0xZeqFQ",
  "wallet_id": "545135a4-ecbc-4400-8594-bdb74c51c88d",
  "wallet_label": "Demo Issuer",
  "wallet_name": "Faber",
  "created_at": "2023-11-20T09:49:45.809544Z",
  "updated_at": "2023-11-20T09:49:45.841851Z",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
  "group_id": "API demo"
}

A unique wallet_id has been generated, and this is the identifier for the tenant/wallet. You'll notice in the Swagger docs that wallet_id is used in the /tenant-admin endpoints, and in the /sse endpoints to listen for webhook events.

Note down the access_token, as this is what must be used as x-api-key in order to act as this tenant (e.g. to fetch connections or to accept credentials for this wallet), and it is also used to authenticate the /webhooks and /sse endpoints.

Onboard Verifier​

curl -X 'POST' \
  'https://cloudapi.test.didxtech.com/tenant-admin/v1/tenants' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Token>' \
  -d '{
  "wallet_label": "Demo Verifier",
  "wallet_name": "Acme",
  "roles": [
    "verifier"
  ],
  "group_id": "API demo",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png"
}'

Response:

{
  "access_token": "tenant.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXRfaWQiOiI5Mjg5MzY1OC1mZTJkLTRmMmQtODI2OC1hNjBhNjAxOTQ1YTkiLCJpYXQiOjE3MDA2MzE2MTd9.E5USXOEmKlpZelGzwGs7VxZWfQzvOBPADB2r95pyuWA",
  "wallet_id": "92893658-fe2d-4f2d-8268-a60a601945a9",
  "wallet_label": "Demo Verifier",
  "wallet_name": "Acme",
  "created_at": "2023-11-22T05:40:16.606565Z",
  "updated_at": "2023-11-22T05:40:16.630619Z",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
  "group_id": "API demo"
}

Onboard Holder​

curl -X 'POST' \
  'https://cloudapi.test.didxtech.com/tenant-admin/v1/tenants' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Token>' \
  -d '{
  "wallet_label": "Demo Holder",
  "wallet_name": "Alice",
  "group_id": "API demo",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png"
}'

Response:

{
  "access_token": "tenant.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3YWxsZXRfaWQiOiIyMjcxZjdmMi03MzU5LTRkMDgtYWI2Ni0xMWI2NjFlZDA5ZjQiLCJpYXQiOjE3MDA2MzE2OTN9.uKfcvq06KSlLHlGkH9zaXHcFA3V2WzNvxRVbyNgjXNc",
  "wallet_id": "2271f7f2-7359-4d08-ab66-11b661ed09f4",
  "wallet_label": "Demo Holder",
  "wallet_name": "Alice",
  "created_at": "2023-11-22T05:41:32.662976Z",
  "updated_at": "2023-11-22T05:41:32.707778Z",
  "image_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Example.png",
  "group_id": "API demo"
}

Next: Create Credential Schema